home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1994 November: Tool Chest / Dev.CD Nov 94.toast / Sample Code / MoreFiles 1.2.1 / MoreDesktopMgr.h < prev    next >
Encoding:
C/C++ Source or Header  |  1994-06-29  |  10.1 KB  |  312 lines  |  [TEXT/KAHL]
  1. /*
  2. **    Apple Macintosh Developer Technical Support
  3. **
  4. **    A collection of useful high-level Desktop Manager routines.
  5. **    If the Desktop Manager isn't available, use the Desktop file
  6. **    for 'read' operations.
  7. **
  8. **    We do more because we can...
  9. **
  10. **    by Jim Luther and Nitin Ganatra, Apple Developer Technical Support
  11. **
  12. **    File:    MoreDesktopMgr.h
  13. **
  14. **    Copyright © 1992-1994 Apple Computer, Inc.
  15. **    All rights reserved.
  16. **
  17. **    You may incorporate this sample code into your applications without
  18. **    restriction, though the sample code has been provided "AS IS" and the
  19. **    responsibility for its operation is 100% yours.  However, what you are
  20. **    not permitted to do is to redistribute the source as "DSC Sample Code"
  21. **    after having made changes. If you're going to re-distribute the source,
  22. **    we require that you make it clear in the source that the code was
  23. **    descended from Apple Sample Code, but that you've made changes.
  24. */
  25.  
  26. #ifndef __MOREDESKTOPMGR__
  27.  
  28.  
  29. #ifndef __TYPES__
  30. #include <Types.h>
  31. #endif
  32.  
  33. #ifndef __ERRORS__
  34. #include <Errors.h>
  35. #endif
  36.  
  37. #ifndef __MEMORY__
  38. #include <Memory.h>
  39. #endif
  40.  
  41. #ifndef __OSUTILS__
  42. #include <OSUtils.h>
  43. #endif
  44.  
  45. #ifndef __FILES__
  46. #include <Files.h>
  47. #endif
  48.  
  49. #ifndef __FOLDERS__
  50. #include <Folders.h>
  51. #endif
  52.  
  53. #ifndef __RESOURCES__
  54. #include <Resources.h>
  55. #endif
  56.  
  57. #ifndef __ICONS__
  58. #include <Icons.h>
  59. #endif
  60.  
  61. #ifndef __MOREFILES__
  62. #include "MoreFiles.h"
  63. #endif
  64.  
  65. #ifndef __MOREFILESEXTRAS__
  66. #include "MoreFilesExtras.h"
  67. #endif
  68.  
  69. /*****************************************************************************/
  70.  
  71. pascal    OSErr    DTOpen(StringPtr volName,
  72.                        short vRefNum,
  73.                        short *dtRefNum,
  74.                        Boolean *newDTDatabase);
  75. /*    ¶ Open a volume's desktop database and return the desktop database refNum.
  76.     The DTOpen function opens a volume's desktop database. It returns
  77.     the reference number of the desktop database and indicates if the
  78.     desktop database was created as a result of this call (if it was created,
  79.     then it is empty).
  80.  
  81.     volName            input:    A pointer to the name of a mounted volume
  82.                             or nil.
  83.     vRefNum            input:    Volume specification.
  84.     dtRefNum        output:    The reference number of Desktop Manager's
  85.                             desktop database on the specified volume.
  86.     newDTDatabase    output:    true if the desktop database was created as a
  87.                             result of this call and thus empty.
  88.                             false if the desktop database was already created,
  89.                             or if it could not be determined if it was already
  90.                             created.
  91. */
  92.  
  93. /*****************************************************************************/
  94.  
  95. pascal    OSErr    DTGetAPPL(StringPtr volName,
  96.                           short vRefNum,
  97.                           OSType creator,
  98.                           short *applVRefNum,
  99.                           long *applParID,
  100.                           Str255 applName);
  101. /*    ¶ Find an application on a volume that can open a file with a given creator.
  102.     The DTGetAPPL function finds an application (file type 'APPL') with
  103.     the specified creator on the specified volume. It first tries to get
  104.     the application mapping from the desktop database. If that fails, then
  105.     it tries to find an application with the specified creator using
  106.     the File Manager's CatSearch routine. If that fails, then it tries to
  107.     find an application in the Desktop file.
  108.  
  109.     volName        input:    A pointer to the name of a mounted volume
  110.                         or nil.
  111.     vRefNum        input:    Volume specification.
  112.     creator        input:    The file's creator type.
  113.     applVRefNum    output:    The volume reference number of the volume the
  114.                         application is on.
  115.     applParID    output:    The parent directory ID of the application.
  116.     applName    output:    The name of the application.
  117.  
  118.     __________
  119.     
  120.     Also see:    FSpDTGetAPPL
  121. */
  122.  
  123. /*****************************************************************************/
  124.  
  125. pascal    OSErr    FSpDTGetAPPL(StringPtr volName,
  126.                              short vRefNum,
  127.                              OSType creator,
  128.                              FSSpec *spec);
  129. /*    ¶ Find an application on a volume that can open a file with a given creator.
  130.     The FSpDTGetAPPL function finds an application (file type 'APPL') with
  131.     the specified creator on the specified volume. It first tries to get
  132.     the application mapping from the desktop database. If that fails, then
  133.     it tries to find an application with the specified creator using
  134.     the File Manager's CatSearch routine. If that fails, then it tries to
  135.     find an application in the Desktop file.
  136.  
  137.     volName        input:    A pointer to the name of a mounted volume
  138.                         or nil.
  139.     vRefNum        input:    Volume specification.
  140.     creator        input:    The file's creator type.
  141.     spec        output:    FSSpec record containing the application name and
  142.                         location.
  143.  
  144.     __________
  145.     
  146.     Also see:    DTGetAPPL
  147. */
  148.  
  149. /*****************************************************************************/
  150.  
  151. pascal    OSErr    DTGetIcon(StringPtr volName,
  152.                           short vRefNum,
  153.                           short iconType,
  154.                           OSType fileCreator,
  155.                           OSType fileType,
  156.                           Handle *iconHandle);
  157. /*    ¶ Get an icon from the desktop database or Desktop file.
  158.     The DTGetIcon function retrieves the specified icon and returns it in
  159.     a newly created handle. The icon is retrieves from the Desktop Manager
  160.     or if the Desktop Manager is not available, from the Finder's Desktop
  161.     file. Your program is responsible for disposing of the handle when it is
  162.     done using the icon.
  163.  
  164.     volName        input:    A pointer to the name of a mounted volume
  165.                         or nil.
  166.     vRefNum        input:    Volume specification.
  167.     iconType    input:    The icon type as defined in Files.h. Valid values are:
  168.                             kLargeIcon
  169.                             kLarge4BitIcon
  170.                             kLarge8BitIcon
  171.                             kSmallIcon
  172.                             kSmall4BitIcon
  173.                             kSmall8BitIcon
  174.     fileCreator    input:    The icon's creator type.
  175.     fileType    input:    The icon's file type.
  176.     iconHandle    output:    A Handle containing the newly created icon.
  177. */
  178.  
  179. /*****************************************************************************/
  180.  
  181. pascal    OSErr    DTSetComment(short vRefNum,
  182.                              long dirID,
  183.                              StringPtr name,
  184.                              ConstStr255Param comment);
  185. /*    ¶ Set a file or directory's Finder comment field.
  186.     The DTSetComment function sets a file or directory's Finder comment
  187.     field. The volume must support the Desktop Manager because you only
  188.     have read access to the Desktop file.
  189.  
  190.     vRefNum    input:    Volume specification.
  191.     dirID    input:    Directory ID.
  192.     name    input:    Pointer to object name, or nil when dirID
  193.                     specifies a directory that's the object.
  194.     comment    input:    The comment to add. Comments are limited to 200 characters;
  195.                     longer comments are truncated.
  196.  
  197.     __________
  198.     
  199.     Also see:    DTCopyComment, FSpDTCopyComment, FSpDTSetComment, DTGetComment,
  200.                 FSpDTGetComment
  201. */
  202.  
  203. /*****************************************************************************/
  204.  
  205. pascal    OSErr    FSpDTSetComment(const FSSpec *spec,
  206.                                 ConstStr255Param comment);
  207. /*    ¶ Set a file or directory's Finder comment field.
  208.     The FSpDTSetComment function sets a file or directory's Finder comment
  209.     field. The volume must support the Desktop Manager because you only
  210.     have read access to the Desktop file.
  211.  
  212.     spec    input:    An FSSpec record specifying the file or directory.
  213.     comment    input:    The comment to add. Comments are limited to 200 characters;
  214.                     longer comments are truncated.
  215.  
  216.     __________
  217.     
  218.     Also see:    DTCopyComment, FSpDTCopyComment, DTSetComment, DTGetComment,
  219.                 FSpDTGetComment
  220. */
  221.  
  222. /*****************************************************************************/
  223.  
  224. pascal    OSErr    DTGetComment(short vRefNum,
  225.                              long dirID,
  226.                              StringPtr name,
  227.                              Str255 comment);
  228. /*    ¶ Get a file or directory's Finder comment field (if any).
  229.     The DTGetComment function gets a file or directory's Finder comment
  230.     field (if any) from the Desktop Manager or if the Desktop Manager is
  231.     not available, from the Finder's Desktop file.
  232.  
  233.     vRefNum    input:    Volume specification.
  234.     dirID    input:    Directory ID.
  235.     name    input:    Pointer to object name, or nil when dirID
  236.                     specifies a directory that's the object.
  237.     comment    output:    A Str255 where the comment is to be returned.
  238.  
  239.     __________
  240.     
  241.     Also see:    DTCopyComment, FSpDTCopyComment, DTSetComment, FSpDTSetComment,
  242.                 FSpDTGetComment
  243. */
  244.  
  245. /*****************************************************************************/
  246.  
  247. pascal    OSErr    FSpDTGetComment(const FSSpec *spec,
  248.                                 Str255 comment);
  249. /*    ¶ Get a file or directory's Finder comment field (if any).
  250.     The FSpDTGetComment function gets a file or directory's Finder comment
  251.     field (if any) from the Desktop Manager or if the Desktop Manager is
  252.     not available, from the Finder's Desktop file.
  253.  
  254.     spec    input:    An FSSpec record specifying the file or directory.
  255.     comment    output:    A Str255 where the comment is to be returned.
  256.  
  257.     __________
  258.     
  259.     Also see:    DTCopyComment, FSpDTCopyComment, DTSetComment, FSpDTSetComment,
  260.                 DTGetComment
  261. */
  262.  
  263. /*****************************************************************************/
  264.  
  265. pascal    OSErr    DTCopyComment(short srcVRefNum,
  266.                               long srcDirID,
  267.                               StringPtr srcName,
  268.                               short dstVRefNum,
  269.                               long dstDirID,
  270.                               StringPtr dstName);
  271. /*    ¶ Copy the file or folder comment from the source to the destination object.
  272.     The DTCopyComment function copies the file or folder comment from the
  273.     source to the destination object.  The destination volume must support
  274.     the Desktop Manager because you only have read access to the Desktop file.
  275.     
  276.     srcVRefNum    input:    Source volume specification.
  277.     srcDirID    input:    Source directory ID.
  278.     srcName        input:    Pointer to source object name, or nil when srcDirID
  279.                         specifies a directory that's the object.
  280.     dstVRefNum    input:    Destination volume specification.
  281.     dstDirID    input:    Destination directory ID.
  282.     dstName        input:    Pointer to destination object name, or nil when
  283.                         dstDirID specifies a directory that's the object.
  284.  
  285.     __________
  286.     
  287.     Also see:    FSpDTCopyComment, DTSetComment, FSpDTSetComment, DTGetComment,
  288.                 FSpDTGetComment
  289. */
  290.  
  291. /*****************************************************************************/
  292.  
  293. pascal    OSErr    FSpDTCopyComment(const FSSpec *srcSpec,
  294.                                  const FSSpec *dstSpec);
  295. /*    ¶ Copy the desktop database comment from the source to the destination object.
  296.     The FSpDTCopyComment function copies the desktop database comment from
  297.     the source to the destination object.  Both the source and the
  298.     destination volumes must support the Desktop Manager.
  299.     
  300.     srcSpec        input:    An FSSpec record specifying the source object.
  301.     dstSpec        input:    An FSSpec record specifying the destination object.
  302.  
  303.     __________
  304.     
  305.     Also see:    DTCopyComment, DTSetComment, FSpDTSetComment, DTGetComment,
  306.                 FSpDTGetComment
  307. */
  308.  
  309. /*****************************************************************************/
  310.  
  311. #endif
  312.